Summary

This PR introduces a unified configuration abstraction for the B2C SDK and adds a comprehensive plugin hook system for extending CLI functionality. The changes consolidate configuration loading logic, provide a consistent API across CLI and SDK consumers, and enable third-party plugins to inject configuration, middleware, lifecycle hooks, and custom cartridge discovery.

New Extensibility Hooks

HTTP Middleware Hook

Plugins can inject middleware into all HTTP clients (OCAPI, SLAS, WebDAV, etc.) for logging, metrics, custom headers, or request/response transformation.

const provider: HttpMiddlewareProvider = {
  name: 'request-logger',
  getMiddleware(clientType) {
    return {
      onRequest({ request }) {
        console.log(`[${clientType}] ${request.method} ${request.url}`);
        return request;
      },
    };
  },
};

B2C Operation Lifecycle Hook

Plugins can observe and control B2C operation execution with before/after callbacks. The context includes the full B2CInstance for API access.

const provider: B2COperationLifecycleProvider = {
  name: 'audit-logger',
  async beforeOperation(context) {
    // Access context.instance for API calls
    // Return { skip: true } to prevent execution
  },
  async afterOperation(context, result) {
    // Log results, send notifications, etc.
  },
};

Supported operations: job:run, job:import, job:export, code:deploy

Cartridge Providers Hook

Plugins can provide custom cartridge discovery logic (manifest files, remote sources, etc.).

const provider: CartridgeProvider = {
  name: 'manifest-provider',
  priority: 'before', // or 'after' default discovery
  async findCartridges(options) {
    // Return CartridgeMapping[] from custom source
  },
};

Configuration System

New Components

• ConfigResolver - High-level API for resolving configuration from multiple sources
• ConfigSource interface - Extensible protocol for custom config sources
• Built-in sources: DwJsonSource (dw.json), MobifySource (~/.mobify)
• NormalizedConfig - Canonical camelCase format for all configuration
• Hostname mismatch protection - Prevents mixing credentials across instances

Resolution Priority

1. CLI flags and environment variables (highest)
2. Plugin sources with priority: 'before'
3. dw.json configuration file
4. ~/.mobify (MRT API key)
5. Plugin sources with priority: 'after' (lowest)

SDK Changes

New Files

• src/cli/lifecycle.ts - B2C operation lifecycle types and runner
• src/cli/cartridge-providers.ts - Cartridge provider types and runner
• src/clients/middleware-registry.ts - HTTP middleware registry (SDK-level)
• src/config/resolver.ts - Configuration resolver
• src/config/mapping.ts - Config format normalization
• src/config/types.ts - Configuration type definitions

Updated Base Commands

• JobCommand - Lifecycle hook support for job operations
• CartridgeCommand - Lifecycle hooks + cartridge provider integration
• BaseCommand - HTTP middleware and config source collection

HTTP Client Updates

All clients now support middleware from the global registry:

• OCAPI, SLAS, ODS, MRT, Custom APIs - openapi-fetch middleware
• WebDAV - Adapted fetch middleware pattern

Example Plugin

New package @salesforce/b2c-plugin-example-config demonstrating:

• EnvFileSource - Loads configuration from .env.b2c files
• Hook registration with priority ordering

Documentation

• Updated: docs/guide/extending.md - Comprehensive plugin development guide covering all four hooks
• Updated: docs/guide/configuration.md - Resolution priority with plugin sources